# Python virtual environment usage

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

Basic usage of Python virtual environments on Quectel Pi. Virtual environments isolate project dependencies and prevent third-party packages from affecting the system Python environment.

# Environment Verification

First, verify the Python and system environments on the development board:

```bash
python3 --version
cat /etc/os-release
command -v pip3 || echo "pip3 not installed"
```

| **Item** | **Description** |
| --- | --- |
| System | Currently verified on Debian GNU/Linux 13 (trixie) |
| Python | Currently verified with Python 3.13.5 |
| pip3 | pip3 is not detected in the current image by default; install it as needed |

# Creation and Activation

```bash
sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/projects/python-demo
cd ~/projects/python-demo
python3 -m venv .venv
source .venv/bin/activate
```

After activation, use the following commands to confirm that the current interpreter and pip come from the virtual environment:

```bash
which python
which pip
python --version
pip --version
```

# Dependency Management

```bash
python -m pip install --upgrade pip
pip install <package_name>
pip freeze > requirements.txt
pip install -r requirements.txt
```

If the project requires GPIO, serial-port, or networking libraries, install them in the virtual environment. For example:

```bash
pip install pyserial requests python-periphery
```

# Deactivate the Environment

```bash
deactivate
```

# Notes

- `.venv` is generally excluded from version control.

- `requirements.txt` should be maintained with the project so that the environment can be reproduced across multiple development boards.

- On Debian 13, using `--break-system-packages` to modify the system Python environment is not recommended by default.